home *** CD-ROM | disk | FTP | other *** search
/ Collection of Tools & Utilities / Collection of Tools and Utilities.iso / comm / uwpc201.zip / TERMCC.DOC < prev    next >
Text File  |  1991-11-15  |  19KB  |  420 lines
  1.                Termcap Compiler Version 1.01
  2.  
  3.                  Copyright (C) 1991 Rhys Weatherley
  4.  
  5. 1. INTRODUCTION
  6.  
  7. The Termcap Compiler is a tool for creating new terminal emulations for use
  8. with UW/PC (versions 2.00 and higher).  It takes source code in the form of an
  9. abstract assembly code and compiles them into binary terminal descriptions that
  10. UW/PC can use to provide new types of terminal emulations.  The standard UW/PC
  11. terminal types are included as examples of the assembly code versions of the
  12. terminal descriptions in the files VT52.CAP, ADM31.CAP and ANSI.CAP in the
  13. source code archive UW-SRC.ZIP.
  14.  
  15. 2. USING THE TERMCAP COMPILER.
  16.  
  17. The Termcap Compiler "TERMCC" accepts assembly code from the filename supplied
  18. as an argument and writes the resultant compiled terminal description to the
  19. supplied output file or a file with the same path and name as the input file,
  20. but with a ".TRM" extension.  The full command syntax is:
  21.  
  22.     TERMCC infile[.CAP] [outfile[.TRM]]
  23.  
  24. 3. USING NEW TERMINAL DESCRIPTIONS WITH UW/PC.
  25.  
  26. This section explains how you can add terminal descriptions you have written
  27. and compiled to UW/PC so that it will use them during communications.  This
  28. is also explained in "UW.DOC", but is repeated here for convenience.
  29.  
  30. In the configuration file "UW.CFG" for UW/PC the following configuration
  31. options can be specified:
  32.  
  33.     emul (default adm31)
  34.  
  35.         The default terminal emulation type to use for windows.
  36.         When a new window is created, it will use this emulation
  37.         type.  This can be one of adm31, vt52, or ANSI or a string
  38.         (e.g. "vt102"), signifying a currently loaded terminal
  39.         description that will be searched for to become the
  40.         default emulation.  The double quotes are optional.
  41.         When the terminal description is searched for, case is
  42.         ignored during compares.
  43.  
  44.     emul0 (defaults to whatever emul is set to)
  45.  
  46.         Set the terminal emulation type for protocol 0.  This is
  47.         to rectify some problems with UNIX termcap entries that
  48.         are missing the entry for ADM31 terminals, as discussed 
  49.         above under "USING UW/PC".  It can be one of adm31, vt52
  50.         or ansi or a string specifying a terminal type loaded
  51.         with the "terminal" configuration option.
  52.  
  53.     terminal (no default)
  54.  
  55.         This can appear up to five times in the configuration file
  56.         and each occurrence will load a terminal description into
  57.         memory.  It's string value specifies a filename for a
  58.         compiled terminal description.  The full pathname should be
  59.         supplied.  For example, the following line could be added to
  60.         the configuration file to add a "VT102" terminal emulation:
  61.  
  62.             terminal="c:\uw\vt102.trm"
  63.  
  64.         The standard VT52, ADM31 and ANSI terminal types can be
  65.         replaced with new terminal descriptions by loading new
  66.         files that have the VT52, ADM31 or ANSI terminal type
  67.         specified.
  68.  
  69. 4. THE ABSTRACT MACHINE.
  70.  
  71. UW/PC uses a small interpretive abstract machine to decode compiled terminal
  72. descriptions on the fly while performing communications.  Its overhead is
  73. small enough not to have a significant impact on the performance of UW/PC.
  74. This abstract machine has a number of registers that can be accessed from
  75. the assembly code described in the next section.
  76.  
  77.     accumulator    - This is the primary control register.  It holds
  78.               16 bit signed values.
  79.     x register    - This is an auxillary register, primarily used for
  80.               cursor positioning during terminal emulation.  It
  81.               holds 16 bit signed values.
  82.     y register    - This is an auxillary register, primarily used for
  83.               cursor positioning during terminal emulation.  It
  84.               holds 16 bit signed values.
  85.     comparator    - After a comparison instruction, this register will
  86.               hold a value that is inspected during the conditional
  87.               jump instructions.  Its (16 bit) value cannot be
  88.               directly accessed.
  89.     flags        - This is a 16 bit quantity that allows you to record
  90.               up to 16 single bit flags that may be useful for
  91.               recording such information as whether the terminal's
  92.               insertion mode is on or off, etc.
  93.     saved x reg    - An auxillary register that can be used to save the
  94.               terminal's current X cursor co-ordinate.  It's value
  95.               cannot be directly accessed, except through the
  96.               "savexy", "restxy" and "getxy" instructions.
  97.     saved y reg    - An auxillary register that can be used to save the
  98.               terminal's current Y cursor co-ordinate.  It's value
  99.               cannot be directly accessed, except through the
  100.               "savexy", "restxy" and "getxy" instructions.
  101.     saved attribute    - An auxillary register that can be used to save the
  102.               terminal's current printing attribute.  It's value
  103.               cannot be directly accessed, except through the
  104.               "saveattr" and "restattr" instructions.
  105.     argument array    - An array of eight 16-bit quantities that can be used
  106.               to store arguments to escape sequences for emulations
  107.               such as ANSI and VT102 which have variable numbers of
  108.               arguments for their escape sequences.
  109.     number of args    - A 16-bit quantity that normally records how many
  110.               arguments are in the argument array.  It can also
  111.               be used as a loop counter.
  112.  
  113. 5. ASSEMBLY INSTRUCTIONS.
  114.  
  115. This section describes the format of the assembly source file, and the various
  116. instructions that can be used to create terminal descriptions.
  117.  
  118. The source file can contain comments that begin with "//" and continue to the
  119. end of the line (like in C++), and it must begin with a "name" instruction,
  120. although this is not checked by the compiler.  There is no fixed format for
  121. the instructions except that labels cannot occur between an instruction's
  122. name and its arguments.  Other than that, an instruction can appear in any
  123. way with any amount of white space and comments surrounding its name and
  124. arguments, and any number of instructions and labels can appear on the one
  125. line or wrapped across lines.  Despite this, it is better to only place one
  126. instruction on each line with an optional label preceding it, as shown in the
  127. example terminal descriptions.
  128.  
  129. Labels consist of an alphanumeric identifier (that must not be an instruction
  130. name) and a colon.  The two labels "start" and "keys" must be present in the
  131. source file.  "start" indicates where the decoding for output to the terminal
  132. screen begins, and "keys" indicates where the decoding of special keycodes
  133. (for example terminal function keys) begins.  Without these labels, UW/PC
  134. cannot process the terminal description properly.
  135.  
  136. There is one special escape sequence that EVERY terminal type MUST support:
  137. "ESC |".  This will be used by UW/PC together with some of the upcoming
  138. enhancements to UW/PC.  The handling for this escape sequence is to use
  139. "getch" to retrieve the next character after the '|' and then to execute the
  140. "client" instruction.  If a terminal description does not handle this escape
  141. sequence in this way, then the special clients cannot be activated in
  142. windows of that terminal type.
  143.  
  144.     add    - Adds the instruction's argument to the accumulator.
  145.           The argument can be numeric, "width" or "height".
  146.  
  147.     bell    - Ring the terminal bell.
  148.  
  149.     bs    - Move the cursor back one character.  The cursor will
  150.           not wrap around to the previous line if it is at the
  151.           start of the current line.
  152.  
  153.     bswrap    - Move the cursor back one character and wrap around to
  154.           the end of the previous line if necessary.  If the cursor
  155.           is in the top-left screen position, it won't be moved.
  156.  
  157.     clear    - Clear the entire screen to the current scrolling attribute.
  158.           The cursor is not moved from its current position.
  159.  
  160.     client    - This should be executed for the escape sequence ESC '|'.
  161.           UW/PC uses this for some of its specialised clients such
  162.           as the upcoming mail tool uwmail.
  163.  
  164.     clreol    - Clear to the end of the current line in the current
  165.           scrolling attribute.
  166.  
  167.     clreos    - Clear to the end of the screen from the current cursor
  168.           position in the current scrolling attribute.
  169.  
  170.     clrsol    - Clear to the start of the current line in the current
  171.           scrolling attribute.  The current cursor position is
  172.           not cleared.
  173.  
  174.     clrsos    - Clear to the start of the screen from the current
  175.           cursor position in